/*
 * $Id: dll.h,v 1.5 2005-12-11 10:35:08 bacon Exp $
 */

#ifndef _XP_BAS_DLL_H_
#define _XP_BAS_DLL_H_

#include <xp/types.h>
#include <xp/macros.h>

/*
 * TYPE: xp_dll_t
 *   Defines a dynamically loadable library object
 *
 * DESCRIPTION:
 *   <xp_dll_t> wraps the native dynamic library handle of the underlying 
 *   operating system.
 */

typedef struct xp_dll_t xp_dll_t;

struct xp_dll_t
{
	void* handle;
	xp_bool_t __dynamic;
};

#ifdef __cplusplus
extern "C" {
#endif

/*
 * FUNCTION: xp_dll_open
 *   Instantiates a dynamic library object
 *
 * PARAMETERS:
 *   dll - [in] a dynamic library object
 *   path - [in] path to the dynamic library
 * 
 * RETURNS:
 *   Pointer to the instantiated library object on success, *XP_NULL* on failure
 *
 * DESCRIPTION:
 *   <xp_dll_open> instantiates a new object into *dll*, following necessary
 *   memory allocation if *dll* is *XP_NULL*. It returns the address of the
 *   new object. 
 * 
 * SEE ALSO: 
 *   <xp_dll_close> <xp_dll_lookup>
 */
xp_dll_t* xp_dll_open (xp_dll_t* dll, const xp_char_t* path);

/*
 * FUNCTION: xp_dll_close
 *   Destroys a dynamic library object
 *
 * PARAMETERS:
 *   dll - [in] a dynamic library object
 *
 * RETURNS:
 *   0 on success, -1 on failure
 *
 * SEE ALSO: 
 *   <xp_dll_open> <xp_dll_lookup>
 */
int xp_dll_close (xp_dll_t* dll);

/*
 * FUNCTION: xp_dll_lookup
 *   Resolves a rountine of the name given
 *
 * PARAMETERS:
 *   dll - [in] a dynamic library object
 *   name - [in] the name of the routine to look up
 * 
 * RETURNS:
 *   Address of the routine found, *XP_NULL* on failure.
 *
 * SEE ALSO: 
 *   <xp_dll_open> <xp_dll_close>
 */
void* xp_dll_lookup (xp_dll_t* dll, const xp_char_t* name);

#ifdef __cplusplus
}
#endif

#endif
